docs: add Kosli Capture Managed Service page - #380

Suggestion — closing fence has four backticks, and neither code block declares a language.

The four-backtick close does still terminate the block under CommonMark, so it renders — but it's a stray character, and neither block (line 20 and line 46) tags a language, so both lose syntax highlighting on what is otherwise a page of YAML.

Change ``` → ```yaml on lines 20 and 46, and:

Critical — relative link. ./kosli_capture_security is the only relative internal link in the repo (grep -rn "](\./" returns just this line). CLAUDE.md core rule 3 requires root-relative paths — relative links break when a page moves, and mint broken-links will flag it.

Two other things on the line: "deep-diver" should be "deep dive", and there's a double space after "permissions."

Critical — this section still refers to an unnamed "customer A". Line 29 reads "Only that role is permitted to call AssumeRole into A's account with A's ExternalId." Nothing on the page defines "A" — it's carried over from an internal design document where customers were labelled A and B. A reader hits an unresolvable pronoun in the one section they are most likely to forward to their security team.

Three more defects in the same block:

• Line 27 has no closing full stop ("...scoped to one customer").
• "Kosli Catpure" appears twice on line 33 — the product name is misspelled. Vale won't catch this: .vale.ini sets BasedOnStyles = Kosli, and styles/Kosli/ contains only AmericanSpelling.yml, so there is no general spellchecker on this repo.
• Line 33 is a comma splice ("...customer data, it is near-stateless...").

(The suggestion also unifies on "external ID", which is the form used on lines 71–73 and on the security page.)

Improvement — GCP and Azure are claimed only here, and the "publicly accessible" template still has no URL.

Two problems in one sentence:

1. GCP/Azure. This says Kosli Capture "uses the public AWS, GCP and Azure APIs", but everything else across both pages is AWS-only: IAM role, CloudFormation, ECS and Lambda policy statements, and kosli_capture.md:57/:63 talk only about AWS accounts. A reader on GCP or Azure is told the service uses their provider's API and then given no mechanism to grant access. The Current status section that used to scope this ("Support for … other cloud providers is in active development") was dropped in 7afa53c, so this is now the only provider-scope statement on either page — and it over-claims.
2. The template URL. "The template is publicly accessible and can be used directly within an aws cloudformation create-stack call" is the most actionable sentence on the page, but the template is named five times across the two pages and never linked. A reader who wants to review the permissions before contacting Customer Success has nowhere to go. If the URL is public, link it and show the create-stack invocation; if it isn't public yet, say "Kosli provides the template during onboarding" so the reader stops looking.

Improvement — stray fourth backtick, and the S3 removal left the block's framing stale.

The closing fence is ```` (four backticks). CommonMark still terminates the block, so it renders — but it's a stray character in the last line of the page.

More substantively: b6dd574 removed the S3BucketMetadataOnly allow and the NeverReadObjectData deny, and with them the comment that explained why the explicit denies exist ("redundant given the allow-list above, but they are here so that a reviewer can verify the boundary…"). The surviving NeverDownloadFunctionCode deny at line 94 is now an unexplained deny in a policy of allows — its own comment explains what it blocks but not why a deny is used rather than simply omitting the action. For a page whose whole purpose is passing a security review, that rationale was worth keeping.

Neither code block declares a language, so both lose highlighting on what is otherwise a page of YAML — change ``` to ```yaml on lines 20 and 46.

Improvement — "all supported resources" is now undefined anywhere on the site, and auto-creation is claimed twice.

The Current status section was removed in 7afa53c, which took with it the only statement of what Kosli Capture can snapshot. As of this HEAD:

• line 57 says "all supported resources" without defining the set;
• line 61 uses ECS clusters and Lambdas as incidental examples;
• the only actual signal is the IAM policy on the security page (ECS + Lambda — S3 was dropped in b6dd574).

So a reader evaluating Kosli Capture has to reverse-engineer the supported resource types from an IAM policy two pages away. One sentence naming them ("Kosli Capture currently snapshots ECS services and Lambda functions") restores what the removed section provided, and keeps this page in sync when S3 or EKS lands.

Separately, environment auto-creation is stated on line 57 ("Kosli Capture will create physical environments for you") and again on line 61 ("Because Kosli Capture creates physical environments as needed, when your infrastructure changes, Kosli will keep up") — the second is circular, restating the claim as its own reason. Folding it into the evolution paragraph lands it once, where it matters.

Improvement — this over-claims against the tag-driven model the page is built on, plus two word-level defects.

"your application teams do not need to take any action in order to onboard their products and services into Kosli" contradicts lines 18, 23 and 57, which all say routing is driven by your tagging scheme. An untagged new service can't be routed into an environment — so the action app teams do need to take is tagging their resources to the scheme. Saying that is more useful than claiming zero action, and it's exactly what a platform team needs to pass on.

Also on this line: "rotation of API keys is all handed automatically" → "handled", and "Kosli capture" is lowercase twice (capitalized everywhere else on the page). Neither is caught by vale-spellcheck — styles/Kosli/ only holds AmericanSpelling.yml.

Suggestion — duplicated word, and the bullets use semicolon terminators.

"to this this architecture" has a doubled "this". Also, the two bullets end in ; and . and begin lowercase — every other bulleted list in this file and in kosli_capture_security.md uses sentence-cased bullets (see lines 29–31).

Suggestion — this section duplicates the dedicated security page without linking to it.

administration/kosli_capture_security.md is the sibling page in the new nav group, and its whole subject is this. The only link between the two pages is buried at line 69 under "IAM permissions" (and is relative — see the other comment). A reader who stops at this section never learns the deeper page exists.

A single forward pointer at the end of this section, e.g. "For the IAM role, trust policy and full permission list, see Kosli Capture security." — the security page has no link back to the overview either, so the pair is currently only navigable via the sidebar.

Improvement — this section still refers to an unnamed "customer A". Line 29 reads "Only that role is permitted to call AssumeRole into A's account with A's ExternalId." Nothing on the page defines "A" — it reads as a leftover from an internal design document where customers were labelled A and B. This is the one section a reader is most likely to forward to their own security team, and it contains an unresolvable pronoun.

Two more defects in the same block: line 27 has no closing full stop ("...scoped to one customer"), and line 33 is a comma splice ("...customer data, it is near-stateless...") whose second clause also doesn't parse ("with the only thing it keeps is your configuration data").

(The suggestion also unifies on "external ID", the form used on lines 71–73 and on the security page.)

Improvement — GCP and Azure are claimed only here, and the "publicly accessible" template still has no URL.

Two problems in one sentence:

1. GCP/Azure. This says Kosli Capture "uses the public AWS, GCP and Azure APIs", but every mechanism described across both pages is AWS-only: an IAM role, a CloudFormation template, and ECS/Lambda policy statements. kosli_capture/overview.md:57 and :65 talk only about AWS accounts and regions. The Current status section that used to scope this ("Support for … other cloud providers is in active development") was dropped in 7afa53c, so this line is now the only provider-scope statement on either page — and it over-claims. A reader on GCP or Azure is told their provider's API is used and then given no way to grant access.
2. The template URL. "The template is publicly accessible and can be used directly within an aws cloudformation create-stack call" is the most actionable sentence on the page, but the template is named five times across the two pages and never once linked. A reader who wants to review the permissions before contacting Customer Success has nowhere to go. If the URL is public, link it and show the create-stack invocation. If it is not public yet, say "Kosli provides the template during onboarding" so the reader stops looking.

Improvement — "all supported resources" is no longer defined anywhere on the site.

7afa53c removed the Current status section, which was the only statement of what Kosli Capture can snapshot, and b6dd574 then dropped the S3 statements from the policy on the security page. At this HEAD:

• line 57 says "all supported resources" without defining the set;
• line 61 uses ECS clusters and Lambdas only as incidental examples;
• the only real signal is the IAM policy on security.md (ECS + Lambda).

So a reader evaluating Kosli Capture has to reverse-engineer the supported resource types from an IAM policy on another page. One sentence naming them restores what the removed section provided, and gives you an obvious place to update when S3 or EKS lands.

Separately, environment auto-creation is claimed twice — line 57 ("Kosli Capture will create physical environments for you") and again on line 61 ("Because Kosli Capture creates physical environments as needed, when your infrastructure changes, Kosli will keep up"), where it is restated as its own reason. Folding it into the evolution paragraph lands it once, in the place where it matters.

Improvement — the closing clause over-claims against the tag-driven model this page is built on.

"your application teams do not need to take any action in order to onboard their products and services into Kosli" contradicts lines 18, 23 and 57, which all say routing is driven by your tagging scheme. An untagged new service cannot be routed into an environment, so the action app teams do need to take is tagging their resources to the scheme. Stating that is more useful than claiming zero action — it is exactly the instruction a platform team needs to pass on, and it is the one thing that will generate support tickets if left unsaid.

Improvement — with the pages now split, this section and ## Security above duplicate the dedicated security page.

6e1d5c5 gave Kosli Capture its own folder with security.md as a sibling, but the overview still carries two sections on the same subject: ## Security (lines 25–33, the worker/role isolation model) and ## IAM permissions (this section, the trust policy and external ID). security.md covers the trust policy in full, including the actual AssumeRolePolicyDocument, so lines 71–73 are a prose restatement of a YAML block one click away — and the two will drift.

Worth deciding what each page owns. A reasonable split: the overview says what access is needed and why it is safe in two or three sentences, and the security page owns the mechanism. Right now the only link between them is buried at the end of line 69, and security.md has no link back — the pair is navigable only via the sidebar.

Two things on line 69 itself: "deep-diver" should be "deep dive", and there is a double space before "The".

Suggestion — the S3 removal left this deny unexplained, and the closing fence has four backticks.

b6dd574 removed the S3BucketMetadataOnly allow and the NeverReadObjectData deny, and with them the comment that explained why explicit denies appear in an allow-list policy at all ("redundant given the allow-list above, but they are here so that a reviewer can verify the boundary…"). NeverDownloadFunctionCode is now the only deny in a policy of allows: its comment says what it blocks, but not why a deny is used rather than simply omitting the action. On a page whose purpose is passing someone else's security review, that rationale was the valuable part.

Also, line 100 closes with (four backticks). CommonMark still terminates the block so it renders, but it is a stray character on the last line of the page. And neither block on this page (lines 20 and 46) declares a language, so a page that is entirely YAML gets no syntax highlighting — worth changing both openers to ```yaml ````.

Suggestion — doubled word, and these two bullets are punctuated unlike every other list on the pages.

"to this this architecture" has a doubled "this". The bullets also start lowercase and terminate with ; / ., whereas the bulleted lists at lines 29–31 and on the security page are sentence-cased.